<!DOCTYPE html>
<!--
     SPDX-License-Identifier: CC-BY-SA-4.0
     SPDX-FileCopyrightText: 2020 seL4 Project a Series of LF Projects, LLC.
-->
<!-- Page last generated 2025-02-20 03:16:15 +0000 -->
<html lang="en">
  <head>
    <meta charset="utf-8">
    <meta http-equiv="X-UA-Compatible" content="IE=edge">
    <meta name="viewport" content="width=device-width, initial-scale=1">
    <title>Hello CAmkES | seL4 docs</title>

    <!-- Our stylesheet and theme stylesheet.  Contains bootstrap. -->
    <link rel="stylesheet" href="/assets/css/style.css" type="text/css">
    <!-- Font awesome -->
    <link href="https://use.fontawesome.com/releases/v5.0.8/css/all.css" rel="stylesheet">
    <link href="https://fonts.googleapis.com/css2?family=Roboto&display=swap" rel="stylesheet">
    <!-- Pygments syntax highlighting  -->
    <link rel="stylesheet" href="/assets/css/highlighting/trac.css" type="text/css">
    <link rel="icon" type="image/x-icon" href="/assets/favicon.ico"><script defer data-domain="docs.sel4.systems"
	    src="https://analytics.sel4.systems/js/script.js"></script></head>

  <body class="container-fluid">

    



<header>
  <ul class="row menu">
    <li class="col-xs-12 col-md-2" >
            <a href="https://sel4.systems" class="skip-icon">
              <img class="img-responsive" src="/assets/logo-text-white.svg" alt="seL4 logo" />
            </a>
    </li>
    <li class="col-xs-12 col-md-10 menu">
      <nav aria-label="Banner links">
        <h2><a href="/Resources" />Resources</h2>
        <h2><a href="/processes" />Contributing</a></h2>
        <h2><a href="/projects" />Projects</h2>
        <h2><a href="/Tutorials" />Tutorials</h2>
        <iframe title="DuckDuckGo search bar" src="https://duckduckgo.com/search.html?site=docs.sel4.systems&prefill=Search%20sel4.systems" style="overflow:hidden;margin-bottom:10px; padding:0;height:40px;float:right;border-width: 0px"></iframe>
      </nav>
    </li>
  </ul>
  <div class="clear"></div>
  
<div class="breadcrumbs bootstrap hidden-sm-down">
  <nav class="sel-breadcrumb" aria-label="Breadcrumb" >
    <ol class=" list-unstyled" vocab="http://schema.org/" typeof="BreadcrumbList">
      
      
        

        

        <li class="breadcrumb-item" property="itemListElement" typeof="ListItem">
            <a property="item" typeof="WebPage" href="/">
              <span property="name"><b>seL4 Docs</b></span>
            </a>
            <meta property="position" content="1" />
        </li>
      
        

        

        <li class="breadcrumb-item" property="itemListElement" typeof="ListItem">
            <a property="item" typeof="WebPage" href="/Tutorials/">
              <span property="name"><b>Tutorials</b></span>
            </a>
            <meta property="position" content="2" />
        </li>
      
        

        
          <li class="breadcrumb-item" property="itemListElement" typeof="ListItem">
            <span property="name">Hello CAmkES</span>
            <meta property="position" content="3" /></li>
          
    </ol>
  </nav>
  <nav class="sel-version" aria-label="Current Versions">
    <ol class="list-unstyled">
      <li class="list-unstyled text-right" style="margin-left:auto; padding:0rem 0rem;">
        Current versions:</li>
      <li class="list-unstyled text-right">
      <a href="/releases/sel4/13.0.0"><b>seL4-13.0.0</b></a></li>
      <li class="list-unstyled text-right">
      <a href="/releases/microkit/1.4.1"><b>microkit-1.4.1</b></a></li>
      <li class="list-unstyled text-right">
      <a href="/releases/camkes/camkes-3.11.0"><b>camkes-3.11.0</b></a></li>
      <li class="list-unstyled text-right">
      <a href="/releases/capdl/0.3.0"><b>capDL-0.3.0</b></a></li>
      </ol>
  </nav>
  <div class='clear'></div>
</div>


</header>

    <main>
      <div class="row">
  <div class="hidden-xs col-sm-4 col-md-3 col-lg-2">
    

<div class="sidebar">
  <ul class="nav nav-sidebar tutorial-sidebar">
    <li class="nav-section">Getting started</li>
      <li><a href="/Tutorials/">Overview</a></li>
      <li><a href="/Tutorials/pathways">Tutorial pathways</a></li>
    <li class="nav-section">seL4</li>
      <li><a href="/Tutorials/setting-up">Setting up your machine</a></li>
      <li><a href="/Tutorials/get-the-tutorials">Getting the tutorials</a></li>
      <li><a href="/Tutorials/hello-world">Hello world</a></li>
      <li><a href="/Tutorials/capabilities">Capabilities</a></li>
      <li><a href="/Tutorials/untyped">Untyped</a></li>
      <li><a href="/Tutorials/mapping">Mapping</a></li>
      <li><a href="/Tutorials/threads">Threads</a></li>
      <li><a href="/Tutorials/ipc">IPC</a></li>
      <li><a href="/Tutorials/notifications">Notifications</a></li>
      <li><a href="/Tutorials/interrupts">Interrupts</a></li>
      <li><a href="/Tutorials/fault-handlers">Fault handling</a></li>
      <li><a href="/Tutorials/mcs">MCS extensions</a></li>
    <li class="nav-section">C Libraries</li>
      <li><a href="/Tutorials/libraries-1">Initialisation &amp; threading</a></li>
      <li><a href="/Tutorials/libraries-2">IPC</a></li>
      <li><a href="/Tutorials/libraries-3">Processes &amp; Elf loading</a></li>
      <li><a href="/Tutorials/libraries-4">Timer</a></li>
    <li class="nav-section">Microkit</li>
      <li><a href="https://trustworthy.systems/projects/microkit/tutorial/">Tutorial</a></li>
    <li class="nav-section">CAmkES</li>
      <li><a href="/Tutorials/hello-camkes-0">Hello CAmkES</a></li>
      <li><a href="/Tutorials/hello-camkes-1">Introduction to CAmkES</a></li>
      <li><a href="/Tutorials/hello-camkes-2">Events in CAmkES</a></li>
      <li><a href="/Tutorials/hello-camkes-timer">CAmkES timer tutorial</a></li>
      <li><a href="/Tutorials/camkes-vm-linux">CAmkES VM</a></li>
      <li><a href="/Tutorials/camkes-vm-crossvm">CAmkES cross-VM connectors</a></li>
    <li class="nav-section">Rust</li>
      <li><a href="https://github.com/seL4/rust-sel4">GitHub</a></li>
    <li class="nav-section">Resources</li>
      <li><a href="https://sel4.systems/Info/Docs/seL4-manual-latest.pdf">seL4 Manual</a></li>
      <li><a href="/projects/sel4/api-doc.html">seL4 API reference</a></li>
      <li><a href="/Tutorials/how-to">How to: a quick solutions guide</a></li>
      <li><a href="/projects/sel4-tutorials/debugging-guide">Debugging guide</a></li>
      <li><a href="/Resources#contact">Help contacts</a></li>
  </ul>
</div>

  </div>
  <div class="content col-sm-8 col-md-6 col-lg-7 main">

    
<!--
  Copyright 2017, Data61, CSIRO (ABN 41 687 119 230)

  SPDX-License-Identifier: BSD-2-Clause
-->

<h1 id="hello-camkes">Hello CAmkES</h1>

<p>This tutorial is an introduction to CAmkES. This will involve introducing the CAmkES syntax, bootstrapping a basic
static CAmkES application and describing its components.</p>

<p>Outcomes:</p>
<ol>
  <li>Understand the structure of a CAmkES application, as a described, well-defined, static system.</li>
  <li>Understand the file-layout of a CAmkES ADL project.</li>
  <li>Become acquainted with the basics of creating a practical CAmkES application.</li>
</ol>

<p>Use this <a href="https://github.com/seL4/sel4-tutorials/blob/master/docs/CAmkESTutorial.pdf">slide presentation</a> to guide you through the tutorials <a href="/Tutorials/hello-camkes-0">0</a>, <a href="/Tutorials/hello-camkes-1">1</a> and <a href="/Tutorials/hello-camkes-2">2</a>.</p>

<h2 id="prerequisites">Prerequisites</h2>
<ol>
  <li><a href="/Tutorials/setting-up">Set up your machine</a>.</li>
  <li><a href="/Tutorials/hello-world">Hello world tutorial</a></li>
  <li>Familiarise yourself with the <a href="https://github.com/seL4/camkes-tool/blob/master/docs/index.md">CAmkES manual</a>.
Note that it’s possible to successfully complete the CAmkES tutorial without having read the manual, however highly
recommended.</li>
</ol>

<h2 id="background">Background</h2>

<p>The fundamentals of CAmkES are the component, the interface and the connection. Components are logical
groupings of code and resources. They communicate with other component instances via well-defined
interfaces which must be statically defined, over communication channels.</p>

<h3 id="component">Component</h3>

<p>As briefly described above, we identify a component as a functional grouping of code and resources. We
use the term component in CAmkES to refer to the <em>type</em> of our functional grouping (see the Component section in the <a href="https://github.com/seL4/camkes-tool/blob/master/docs/index.md#component">manual</a>).
An example of this in concrete CAmkES syntax can be seen below:</p>

<div class="language-c highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="n">component</span> <span class="n">foo</span> <span class="p">{</span>
  <span class="n">control</span><span class="p">;</span>
  <span class="n">uses</span> <span class="n">MyInterface</span> <span class="n">a</span><span class="p">;</span>
  <span class="n">attribute</span> <span class="n">Int</span> <span class="n">b</span><span class="p">;</span>
<span class="p">}</span>
</code></pre></div></div>

<p>Disregarding the items defined within the component (we will unpack these in a later tutorial), we defined a component above
whose <em>type</em> is <code class="language-plaintext highlighter-rouge">foo</code>. We later can use our <code class="language-plaintext highlighter-rouge">foo</code> type to define a component <em>instance</em>.
For example, the statement <code class="language-plaintext highlighter-rouge">component foo bar</code> refers to a component instance <code class="language-plaintext highlighter-rouge">bar</code> whose type is
<code class="language-plaintext highlighter-rouge">foo</code>.</p>

<h3 id="describing-a-static-system-assembly-composition-and-configuration">Describing a static system: Assembly, Composition and Configuration</h3>

<p>In CAmkES, we will commonly see the use of three hierarchical elements, being <code class="language-plaintext highlighter-rouge">assembly</code>, <code class="language-plaintext highlighter-rouge">composition</code> and <code class="language-plaintext highlighter-rouge">configuration</code>. We use these concepts
to build upon a well-defined static system. We firstly use the term ‘assembly’ to refer to a complete description of our static system. In the CAmkES ADL (Architecture Description Language),
we employ the term <code class="language-plaintext highlighter-rouge">assembly</code> as a top-level element that will encapsulate our system definition. Each CAmkES project must contain
at least one <code class="language-plaintext highlighter-rouge">assembly</code> definition. An example of using the <code class="language-plaintext highlighter-rouge">assembly</code> term in CAmkES can be seen below:</p>

<div class="language-c highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="n">assembly</span> <span class="p">{</span>
  <span class="n">composition</span> <span class="p">{</span>
    <span class="n">component</span> <span class="n">foo</span> <span class="n">bar</span><span class="p">;</span>
  <span class="p">}</span>

  <span class="n">configuration</span> <span class="p">{</span>
      <span class="n">bar</span><span class="p">.</span><span class="n">b</span> <span class="o">=</span> <span class="mi">0</span><span class="p">;</span>
  <span class="p">}</span>
<span class="p">}</span>
</code></pre></div></div>

<p>In the above example we can also see the use of the <code class="language-plaintext highlighter-rouge">composition</code> and <code class="language-plaintext highlighter-rouge">configuration</code> elements. The <code class="language-plaintext highlighter-rouge">composition</code> element is
used as a container to encapsulate our component and connector instantiations. Above we declare an instance of
our <code class="language-plaintext highlighter-rouge">foo</code> component and we appropriately called it <code class="language-plaintext highlighter-rouge">bar</code>. The <code class="language-plaintext highlighter-rouge">configuration</code> element is also used to describe settings and attribute
assignments in our given system.</p>

<h2 id="creating-your-first-camkes-application">Creating your first CAmkES application</h2>

<p>In this tutorial we will create a simple ‘Hello World’ example within the CAmkES. This will invole creating a CAmkES component that will
print “Hello CAmkES World” when it starts up.</p>

<h3 id="looking-at-the-sources">Looking at the sources</h3>

<p>In the tutorial directory, you will find the following files:</p>
<ul>
  <li><code class="language-plaintext highlighter-rouge">CMakeLists.txt</code> - the file that defines how to build our CAmkES application</li>
  <li><code class="language-plaintext highlighter-rouge">client.c</code> - the single source file for our ‘Hello World’ client component</li>
  <li><code class="language-plaintext highlighter-rouge">hello.camkes</code> - Our CAmkES file describing our static system</li>
</ul>

<h4 id="clientc"><code class="language-plaintext highlighter-rouge">client.c</code></h4>

<p>For this tutorial we require our component to simply print “Hello CAmkES World”. We define this in
a typical C file <code class="language-plaintext highlighter-rouge">client.c</code>:</p>

<div class="language-c highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="cm">/*
 * CAmkES tutorial part 0: just a component.
 */</span>

<span class="cp">#include</span> <span class="cpf">&lt;stdio.h&gt;</span><span class="cp">
</span>
<span class="cm">/* generated header for our component */</span>
<span class="cp">#include</span> <span class="cpf">&lt;camkes.h&gt;</span><span class="cp">
</span>
<span class="cm">/* run the control thread */</span>
<span class="kt">int</span> <span class="nf">run</span><span class="p">(</span><span class="kt">void</span><span class="p">)</span> <span class="p">{</span>
    <span class="n">printf</span><span class="p">(</span><span class="s">"Hello CAmkES World</span><span class="se">\n</span><span class="s">"</span><span class="p">);</span>
    <span class="k">return</span> <span class="mi">0</span><span class="p">;</span>
<span class="p">}</span>
</code></pre></div></div>

<p>Note above that in the source code of <code class="language-plaintext highlighter-rouge">client.c</code> instead of typically using <code class="language-plaintext highlighter-rouge">main</code>, we place
our runtime code in the function <code class="language-plaintext highlighter-rouge">int run(void)</code>. <code class="language-plaintext highlighter-rouge">run</code> is the entry point
of a CAmkES component.</p>

<h4 id="hellocamkes"><code class="language-plaintext highlighter-rouge">hello.camkes</code></h4>

<p>The <code class="language-plaintext highlighter-rouge">hello.camkes</code> file is where we form our description of a static CAmkES system. Our <code class="language-plaintext highlighter-rouge">.camkes</code>
files are written using the CAmkES syntax. Employing the concepts discussed in the background
section, we define the following:</p>

<div class="language-c highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="cm">/*
 * CAmkES tutorial part 0: just a component.
 */</span>

<span class="n">component</span> <span class="n">Client</span> <span class="p">{</span>
    <span class="n">control</span><span class="p">;</span>
<span class="p">}</span>

<span class="n">assembly</span> <span class="p">{</span>
    <span class="n">composition</span> <span class="p">{</span>
        <span class="n">component</span> <span class="n">Client</span> <span class="n">client</span><span class="p">;</span>
    <span class="p">}</span>
<span class="p">}</span>
</code></pre></div></div>

<p>In the source above we create a minimal static system with a single component instance. We define
our component <code class="language-plaintext highlighter-rouge">Client</code> and declare an instance of that component in our system.</p>

<h4 id="cmakeliststxt"><code class="language-plaintext highlighter-rouge">CMakeLists.txt</code></h4>

<p>Every CAmkES project requires a <code class="language-plaintext highlighter-rouge">CMakeLists.txt</code> file to be incorporated in the seL4 build system. Our tutorial
directory should contain the following <code class="language-plaintext highlighter-rouge">CMakeLists.txt</code> file:</p>

<div class="language-cmake highlighter-rouge"><div class="highlight"><pre class="highlight"><code>
<span class="nb">include</span><span class="p">(</span><span class="si">${</span><span class="nv">SEL4_TUTORIALS_DIR</span><span class="si">}</span>/settings.cmake<span class="p">)</span>
<span class="nf">sel4_tutorials_regenerate_tutorial</span><span class="p">(</span><span class="si">${</span><span class="nv">CMAKE_CURRENT_SOURCE_DIR</span><span class="si">}</span><span class="p">)</span>

<span class="nb">cmake_minimum_required</span><span class="p">(</span>VERSION 3.7.2<span class="p">)</span>

<span class="nb">project</span><span class="p">(</span>hello-camkes-0 C ASM<span class="p">)</span>

<span class="nb">find_package</span><span class="p">(</span>camkes-tool REQUIRED<span class="p">)</span>
<span class="nf">camkes_tool_setup_camkes_build_environment</span><span class="p">()</span>

<span class="nf">DeclareCAmkESComponent</span><span class="p">(</span>Client SOURCES client.c<span class="p">)</span>

<span class="nf">DeclareCAmkESRootserver</span><span class="p">(</span>hello.camkes<span class="p">)</span>

<span class="nf">GenerateCAmkESRootserver</span><span class="p">()</span>
</code></pre></div></div>

<p>Our <code class="language-plaintext highlighter-rouge">CMakeLists.txt</code> file declares our <code class="language-plaintext highlighter-rouge">Client</code> component, linking it with our <code class="language-plaintext highlighter-rouge">client.c</code> source
file. In addition it declares the CAmkES Root Server using our <code class="language-plaintext highlighter-rouge">hello.camkes</code> system description.</p>

<h3 id="building-your-first-camkes-system">Building your first CAmkES system</h3>

<p>At this point all you need to do is build and run the tutorial:</p>

<div class="language-sh highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="c"># In build directory</span>
ninja
</code></pre></div></div>

<p>If build successfully, we can run our system as follows:</p>

<div class="language-sh highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="c"># In build directory</span>
./simulate
</code></pre></div></div>

<p>and should see the following once the system has booted:</p>

<div class="language-plaintext highlighter-rouge"><div class="highlight"><pre class="highlight"><code>Hello CAmkES World
</code></pre></div></div>

<h2 id="done">Done</h2>
<p>Congratulations: be sure to read up on the keywords and
structure of ADL: it’s key to understanding CAmkES. And well done on
building and running your first CAmkES application.</p>



<p style="text-align: right;">

      Next: <a href="/Tutorials/hello-camkes-1">Introduction to CAmkES</a>
</p>

<hr>
    <p><em>Tutorial included from <a href="https://github.com/sel4/sel4-tutorials/blob/master/tutorials/hello-camkes-0/hello-camkes-0.md">github repo</a> <a href="https://github.com/sel4/sel4-tutorials/edit/master/tutorials/hello-camkes-0/hello-camkes-0.md">edit</a></em></p>
  </div>

  
    
<div class="sidebar-toc hidden-xs hidden-sm col-md-3 col-lg-3">
    <ul id="toc" class="section-nav">
<li class="toc-entry toc-h2"><a href="#prerequisites">Prerequisites</a></li>
<li class="toc-entry toc-h2"><a href="#background">Background</a>
<ul>
<li class="toc-entry toc-h3"><a href="#component">Component</a></li>
<li class="toc-entry toc-h3"><a href="#describing-a-static-system-assembly-composition-and-configuration">Describing a static system: Assembly, Composition and Configuration</a></li>
</ul>
</li>
<li class="toc-entry toc-h2"><a href="#creating-your-first-camkes-application">Creating your first CAmkES application</a>
<ul>
<li class="toc-entry toc-h3"><a href="#looking-at-the-sources">Looking at the sources</a>
<ul>
<li class="toc-entry toc-h4"><a href="#clientc">client.c</a></li>
<li class="toc-entry toc-h4"><a href="#hellocamkes">hello.camkes</a></li>
<li class="toc-entry toc-h4"><a href="#cmakeliststxt">CMakeLists.txt</a></li>
</ul>
</li>
<li class="toc-entry toc-h3"><a href="#building-your-first-camkes-system">Building your first CAmkES system</a></li>
</ul>
</li>
<li class="toc-entry toc-h2"><a href="#done">Done</a></li>
</ul>
</div>

  
</div>
<script src="/assets/js/toggle-markdown.js"></script>

    </main>
    


<footer class="site-footer">

  <h2 class="footer-heading">seL4 docs</h2>

  <div class="footer-col-wrapper">

    <div class="col-md-2">
      



<ul class="social-media-list">
  <li><a href="https://github.com/sel4"><i class="fab fa-github"></i> <span class="username">sel4</span></a></li><li><a href="https://github.com/sel4proj"><i class="fab fa-github"></i> <span class="username">sel4proj</span></a></li>
</ul>

    </div>

    <div class="col-md-8">
      <ul class="list-unstyled">
        <li>
          This site is for displaying seL4 related documentation.  Pull requests are welcome.
        </li>
        
          <li>
            Site last updated: Fri Feb 7 10:17:38 2025 +1100 ee78c8857c
          </li>
          <li>
                Page last updated: Mon Jan 6 18:52:01 2025 +1100 df31e5ccb8
          </li>
        
      </ul>
    </div>
    <div class="col-md-2">
<a href="https://github.com/seL4/docs/blob/master/Tutorials/hello-camkes-0.md">View page on GitHub</a>
      <br />
      <a href="https://github.com/seL4/docs/edit/master/Tutorials/hello-camkes-0.md">Edit page on GitHub</a>
      <br />
      <a href="/sitemap">Sitemap</a>
    </div>

  </div>

</footer>

  </body>
</html>
